Doxygen for generating DXL documentation - seems to work fine!

Hey all,

we are experimenting with Doxygen at the moment (a free documentation system), which allows you to generate a documentation for your sourcecode directly from the source. The results look very promising. Although Doxygen does not support DXL natively, you can tell him to interpret DXL sources as C files which works reasonably good.

So if you have a huge DXL codebase (most companies probably do) and so many include files that you do not even have an idea what all those do - doxygen can probably help you.

It can generate HTML help, Windows help files, Latex, PDF and other outputs and has a lot of features like automatic generation of call-graphs, etc. which seem very nice.

If anyone is interested I will keep you posted about the results we get.

Regards, Mathias
Mathias Mamsch - Sun Dec 06 11:54:52 EST 2009

Re: Doxygen for generating DXL documentation - seems to work fine!
ManuelFelger - Mon Dec 07 04:09:37 EST 2009

Hey Mathias,

I've tried to run doxygen on a few of my dxl scripts, but it doesnt create any output at all, what am i doing wrong?

Regards,
Manuel

Re: Doxygen for generating DXL documentation - seems to work fine!
Mathias Mamsch - Mon Dec 07 07:48:59 EST 2009

ManuelFelger - Mon Dec 07 04:09:37 EST 2009
Hey Mathias,

I've tried to run doxygen on a few of my dxl scripts, but it doesnt create any output at all, what am i doing wrong?

Regards,
Manuel

Manuel, there are lots of different reasons why doxygen will not generate output. Since an example does more than thousand words i attach an example, with a configuration file.

There are many reasons for a missing output. Some I found sofar:
  • wrong config file (DXL files must be explicitly configured to be parsed as C code)
  • incorrect syntax in the file (a forward declaration without a ; will cause the doxygen parsing to fail and doxygen will ignore the file)
  • you forgot the \file statement in the file, or the filename does not match the real filename

The example should generate find. The configuration file is "Doxyfile" (just load it from the wizzard).

Another thing: .inc files seem to be reserved for php source, so doxygen seems to parse them incorrectly even if you specify it to be parsed as C. This will be corrected in a future version of doxygen, as a workaround open doxygen.exe with your favourite hex editor and replace 'inc' with '$$$'. This worked for me :-)

Regards, Mathias
Attachments

attachment_14414463_DXL_Documentation.zip

Re: Doxygen for generating DXL documentation - seems to work fine!
ManuelFelger - Mon Dec 07 08:52:05 EST 2009

Mathias Mamsch - Mon Dec 07 07:48:59 EST 2009
Manuel, there are lots of different reasons why doxygen will not generate output. Since an example does more than thousand words i attach an example, with a configuration file.

There are many reasons for a missing output. Some I found sofar:

  • wrong config file (DXL files must be explicitly configured to be parsed as C code)
  • incorrect syntax in the file (a forward declaration without a ; will cause the doxygen parsing to fail and doxygen will ignore the file)
  • you forgot the \file statement in the file, or the filename does not match the real filename

The example should generate find. The configuration file is "Doxyfile" (just load it from the wizzard).

Another thing: .inc files seem to be reserved for php source, so doxygen seems to parse them incorrectly even if you specify it to be parsed as C. This will be corrected in a future version of doxygen, as a workaround open doxygen.exe with your favourite hex editor and replace 'inc' with '$$$'. This worked for me :-)

Regards, Mathias

Hey Mathias,

Thanks for your comments, they (and the doxygen FAQ's) helped me to configure it correctly!

Regards,
Manuel